﻿ #region Disclaimer/Info
 
 /////////////////////////////////////////////////////////////////////////////////////////////////
 //
 //   File:		IUserService.cs
 //   Website:		http://dexterblogengine.com/
 //   Authors:		http://dexterblogengine.com/About.ashx
 //   Rev:		1
 //   Created:		19/01/2011
 //   Last edit:		19/01/2011
 //   License:		GNU Library General Public License (LGPL)
 //   File:            IUserService.cs
 //   For updated news and information please visit http://dexterblogengine.com/
 //   Dexter is hosted to Codeplex at http://dexterblogengine.codeplex.com
 //   For any question contact info@dexterblogengine.com
 //
 ///////////////////////////////////////////////////////////////////////////////////////////////////
 
 #endregion
 

using System;
using System.Collections.Generic;
using System.Net.Mail;
using Dexter.Core.EventArgs;
using Dexter.Domain.Model;
using Dexter.Domain.Results;

namespace Dexter.Services {
	/// <summary>
	/// 	Rapresents the gateway for all service to save, retrieve and manipulate data for <see cref="User"/> and <see cref="Role"/>.
	/// </summary>
	public interface IUserService : IDomainService {

		/// <summary>
		/// Gets a user with roles fetched by his email.
		/// </summary>
		/// <param name="email">The email of the user.</param>
		/// <returns>An instane of <see cref="User"/> or null if the user will not exist.</returns>
		User GetUserByEmail(MailAddress email);

		/// <summary>
		/// Gets a user with roles fetched by his username.
		/// </summary>
		/// <param name="username">The username of the user.</param>
		/// <returns>An instane of <see cref="User"/> or null if the user will not exist.</returns>
		User GetUserByUsername ( string username );

		/// <summary>
		/// Gets a user with roles fetched by his key.
		/// </summary>
		/// <param name="key">The key.</param>
		/// <returns>An instane of <see cref="User"/> or null if the user will not exist.</returns>
		User GetUserByKey ( int key );
		
		/// <summary>
		/// Saves the specified user into the repository.
		/// </summary>
		/// <param name="item">The item.</param>
		void Save ( User item );

		/// <summary>
		/// Updates the specified user into the repository.
		/// </summary>
		/// <param name="item">The item.</param>
		void Update ( User item );

		/// <summary>
		/// Deletes the specified user into the repository.
		/// </summary>
		/// <param name="item">The item.</param>
		void Delete(User item);

		/// <summary>
		/// Saves the specified role.
		/// </summary>
		/// <param name="role">The role.</param>
		void Save(Role role);
		
		/// <summary>
		/// Return the number of users online in the specified window time.
		/// </summary>
		/// <param name="userIsOnlineTimeWindow">The user is online time window.</param>
		/// <exception cref="ArgumentOutOfRangeException">Will be throw if the 'userIsOnlineTimeWindow' will be lesser than 1.</exception>
		/// <returns>The numbers of users online.</returns>
		int GetNumberOfUsersOnline(int userIsOnlineTimeWindow);

		/// <summary>
		/// Retrieve a list of users with all roles fetched.
		/// </summary>
		/// <param name="pageIndex">Index of the page.</param>
		/// <param name="pageSize">Size of the page.</param>
		///<returns>An concrete implementation of <see cref="IPagedResult{T}"/>. The result will never be null.</returns>
		IPagedResult <User> GetAllUsers ( int pageIndex , int pageSize );

		/// <summary>
		/// Retrieve a list of users with all roles fetched where the username match (%usernameToMatch%) with the passed value.
		/// </summary>
		///<param name="usernameToMatch">The part of the username.</param>
		///<param name="pageIndex">Index of the page.</param>
		/// <param name="pageSize">Size of the page.</param>
		///<returns>An concrete implementation of <see cref="IPagedResult{T}"/>. The result will never be null.</returns>
		IPagedResult <User> FindUsersByName ( string usernameToMatch , int pageIndex , int pageSize );
		
		/// <summary>
		/// Retrieve a list of users with all roles fetched where the email match (%emailToMatch%) with the passed value.
		/// </summary>
		///<param name="emailToMatch">The part of the email.</param>
		///<param name="pageIndex">Index of the page.</param>
		/// <param name="pageSize">Size of the page.</param>
		///<returns>An concrete implementation of <see cref="IPagedResult{T}"/>. The result will never be null.</returns>
		IPagedResult <User> FindUsersByEmail ( string emailToMatch , int pageIndex , int pageSize );

		/// <summary>
		/// Retrieve a list of <see cref="Role"/> without users fetched.
		/// </summary>
		/// <remarks>
		///	 Be careful, because the collection of <see cref="User"/> is not populate, so read this property could cause more queries.
		/// </remarks>
		///<param name="pageIndex">Index of the page.</param>
		/// <param name="pageSize">Size of the page.</param>
		///<returns>An concrete implementation of <see cref="IPagedResult{T}"/>. The result will never be null.</returns>
		IPagedResult<Role> GetAllRoles(int pageIndex, int pageSize);

		/// <summary>
		/// Check if the specified role exist into the repository.
		/// </summary>
		/// <param name="roleName">Name of the role.</param>
		/// <returns><c>True</c> if the role exists. Otherwise <c>false</c>.</returns>
		bool RoleExists ( string roleName );

		/// <summary>
		/// Gets the users in role.
		/// </summary>
		/// <param name="roleName">Name of the role.</param>
		/// <returns></returns>
		IEnumerable<User> GetUsersInRole(string roleName);

		/// <summary>
		/// This event will raise when a list of <see cref="Role"/> will be retrieved by the implementation of <see cref="GetAllRoles(int, int)"/>.
		/// </summary>
		event EventHandler<GenericEventArgs<IPagedResult<Role>>> RolesRetrieved;

		/// <summary>
		/// This event will raise when a list of <see cref="Role"/> will be retrieved by the implementation of <see cref="GetAllRoles(int, int)"/>.
		/// </summary>
		event EventHandler<GenericEventArgs<IPagedResult<User>>> UserRetrieved;

		/// <summary>
		/// This event will raise when a list of <see cref="Role"/> will be retrieved by the implementation of <see cref="GetAllUsers(int, int)"/>.
		/// </summary>
		event EventHandler<GenericEventArgs<IPagedResult<User>>> UsersRetrieved;

		/// <summary>
		/// This event will raise when a list of <see cref="Role"/> will be retrieved by the implementation of <see cref="FindUsersByEmail(string, int, int)"/>.
		/// </summary>
		event EventHandler<GenericEventArgsWithOneParameter<IPagedResult<User>,string >> UsersRetrievedByEmail;

		/// <summary>
		/// This event will raise when a list of <see cref="Role"/> will be retrieved by the implementation of <see cref="FindUsersByName(string, int, int)"/>.
		/// </summary>
		event EventHandler<GenericEventArgsWithOneParameter<IPagedResult<User>,string >> UsersRetrievedByName;

		/// <summary>
		/// This event will raise before a <see cref="User"/> will retrieved by the implementation of <see cref="GetUserByKey(int)"/>.
		/// </summary>
		event EventHandler<CancelEventArgsWithOneParameter<int>> UserRetrievingById;

		/// <summary>
		/// This event will raise when a <see cref="User"/> will be retrieved by the implementation of <see cref="GetUserByKey(int)"/>.
		/// </summary>
		event EventHandler <GenericEventArgsWithOneParameter <User , int>> UserRetrievedById;

		/// <summary>
		/// This event will raise before a <see cref="User"/> will retrieved by the implementation of <see cref="GetUserByUsername(string)"/>.
		/// </summary>
		event EventHandler<CancelEventArgsWithOneParameter<string>> UserRetrievingByUsername;

		/// <summary>
		/// This event will raise when a <see cref="User"/> will be retrieved by the implementation of <see cref="GetUserByUsername(string)"/>.
		/// </summary>
		event EventHandler<GenericEventArgsWithOneParameter<User, string>> UserRetrievedByUsername;

		/// <summary>
		/// This event will raise before a <see cref="User"/> will retrieved by the implementation of <see cref="GetUserByEmail(MailAddress)"/>.
		/// </summary>
		event EventHandler<CancelEventArgsWithOneParameter<MailAddress>> UserRetrievingByEmail;

		/// <summary>
		/// This event will raise when a <see cref="User"/> will be retrieved by the implementation of <see cref="GetUserByEmail(MailAddress)"/>.
		/// </summary>
		event EventHandler<GenericEventArgsWithOneParameter<User, MailAddress>> UserRetrievedByEmail;

		/// <summary>
		/// This event will raise before a <see cref="User"/> will created by the implementation of <see cref="Save(User)"/>.
		/// </summary>
		event EventHandler<CancelEventArgsWithOneParameter<User>> UserCreating;

		/// <summary>
		/// This event will raise when a <see cref="User"/> will be created by the implementation of <see cref="Save(User)"/>.
		/// </summary>
		event EventHandler<GenericEventArgs<User>> UserCreated;

		/// <summary>
		/// This event will raise before a <see cref="User"/> will updated by the implementation of <see cref="Update(User)"/>.
		/// </summary>
		event EventHandler<CancelEventArgsWithOneParameter<User>> UserUpdating;

		/// <summary>
		/// This event will raise when a <see cref="User"/> will be updated by the implementation of <see cref="Update(User)"/>.
		/// </summary>
		event EventHandler<GenericEventArgs<User>> UserUpdated;

		/// <summary>
		/// This event will raise before a <see cref="User"/> will deleted by the implementation of <see cref="Delete(User)"/>.
		/// </summary>
		event EventHandler<CancelEventArgsWithOneParameter<User>> UserDeleting;

		/// <summary>
		/// This event will raise when a <see cref="User"/> will be deleted by the implementation of <see cref="Delete(User)"/>.
		/// </summary>
		event EventHandler<GenericEventArgs<User>> UserDeleted;
	}
}
